Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Performing Geometric Arithmetic With Shapes

GXDifferenceShape

You can use the GXDifferenceShape function to find the geometric difference between two shapes.

void GXDifferenceShape(gxShape target, gxShape operand);

target

On input, a reference to the shape to subtract from. On output, a reference to a shape describing the difference between the two shapes.

operand

A reference to the shape to subtract.

DESCRIPTION

The GXDifferenceShape function subtracts the operand shape from the target shape, reduces and simplifies the result, and stores it in the target shape.

The initial target shape does not have to contain the operand shape; the result of this function is the intersection of the target and operand shapes subtracted from the target shape.

This function considers the shape fill, the style modifications, and the transform mapping of the target and operand shapes: only areas that are drawn are considered when calculating the difference.

The operand shape cannot have one of the framed shape fills (open-frame or closed-frame). The target shape can have one of the framed fills; in this case, the resulting shape is the part of the frame that does not lie within the operand shape.

If you provide a target or operand shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Posts the error shape_operator_may_not_be_a_bitmap
picture	Posts the error shape_operator_may_not_be_a_picture
text	Converts to path shape if other parameter is not an empty shape or a full shape
glyph	Converts to path shape if other parameter is not an empty shape or a full shape
layout	Converts to path shape if other parameter is not an empty shape or a full shape

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
number_of_contours_exceeds_implementation_limit
number_of_points_exceeds_implementation_limit
size_of_path_exceeds_implementation_limit
size_of_polygon_exceeds_implementation_limit
fill_type_not_allowed	(debugging version)
shape_access_not_allowed	(debugging version)
clip_to_frame_shape_unimplemented	(debugging version)
shape_operator_may_not_be_a_bitmap	(debugging version)
shape_operator_may_not_be_a_picture	(debugging version)
Warnings
character_substitution_took_place
font_substitution_took_place
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)

SEE ALSO

For examples using this function, see "Performing Geometric Arithmetic With Shapes" beginning on page 4-60.

For a discussion of geometric arithmetic, see "Geometric Arithmetic" beginning on page 4-21.

For a discussion of shape fills, see Chapter 2, "Geometric Shapes," in this book.

For a discussion of style modifications, see Chapter 3, "Geometric Styles," in this book.

For a discussion of transform mappings, see Inside Macintosh: QuickDraw GX Objects.

For information about related routines, see the description of the GXIntersectShape function on page 4-107, the GXUnionShape function on page 4-109, and the GXReverseDifferenceShape function in the next section.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help